جدولة التحكم في MQTT

تلميح

التحكم ب MQTT المجدول مخصص للرسائل المجدولة مسبقًا. للتحكم المباشر، راجع التحكم المباشر ب MQTT بدلاً من ذلك.

سيساعدك هذا الدليل على تكوين MQTT على Sofar EMS للتحكم ومراقبة تركيب البطاريات والألواح الشمسية عن بُعد.

ما تحتاجه

1. Sofar EMS مع اتصال بالإنترنت.
2. بيانات اعتماد MQTT: يمكن طلبها عن طريق إرسال بريد إلكتروني إلى support@eniris.be.
3. بيئة تطوير بايثون (أو أي عميل MQTT آخر). يستخدم هذا الدليل مثالاً أساسياً مكتوباً بلغة بايثون للبدء في استخدام MQTT وإرسال الأوامر. ننصح باستخدام بايثون لسهولة الاستخدام، ولكن أي عميل MQTT آخر مدعوم.

معلومات إضافية

MQTT هو بروتوكول اتصالات سريع عبر الإنترنت. إنه نظام رسائل نشر/اشتراك، يسمح بوجود اتصال مباشر بين جهازك و Sofar EMS. تُصنف أصولك إلى مجموعات الطاقة الشمسية، البطارية، المركبات الكهربائية، وأنظمة HVAC. في الوقت الحالي، تسمح هذه التكاملات بالتحكم حسب المجموعة، وليس حسب الجهاز.

التكوين للمرة الأولى (نقطة البداية للمستخدمين الجدد)

لدي Sofar EMS أود إعداده للتحكم عن بُعد عبر MQTT.

1. تحقق من شبكتك

تأكد من أن شبكتك تسمح بحركة مرور شبكة MQTT عبر المنفذ 1883. يمكنك القيام بذلك باستخدام الأمر:

nc -zv mqtt.eniris.be 1883

عندما لا يكون هذا الأمر متاحًا، يمكنك بدلاً من ذلك تنزيل وتنفيذ هذا الكود بلغة بايثون.

عندما تكون في شك، استشر مهندس الشبكة الخاص بك أو استخدم مؤقتًا نقطة اتصال 4G/5G الخاصة بهاتفك عند حدوث أخطاء في الاتصال.

ملاحظة

عندما لا يكون المنفذ 1883 متاحًا من شبكتك، نقدم احتياطيًا على المنفذ 80. يمكن تكوين ذلك في عميل MQTT الخاص بك في خطوة لاحقة من هذا الدليل.

2. إضافة الأجهزة الخاصة بك

سجل الدخول إلى واجهة التكليف وتأكد من إضافة الأجهزة إلى Sofar EMS.

3. إضافة إشارة خارجية MQTT

4. تمكين إشارة MQTT عن بُعد

حدد جميع الأجهزة التي ترغب في تضمينها في التحكم عن بُعد عبر MQTT.

5. تمت إضافة الإشارة عن بُعد

تم تنشيط واجهة التحكم عن بُعد ب MQTT الآن على Sofar EMS.

نحن الآن جاهزون لإرسال بعض الأوامر الأساسية باستخدام مثال بسيط. تخبرك عمود الحالة إذا كانت هناك أي أوامر نشطة.

برنامج تجريبي باستخدام بايثون

نقطة انطلاق جيدة هي اختبار تكاملك الجديد من خلال مثال بسيط.

يقوم هذا الرمز التجريبي بعمل بسيط من خلال إرسال الجدول التالي بشكل مستمر:

• البطارية: ابدأ بالشحن بسرعة 5 كيلووات لمدة 15 دقيقة في كل 10 دقائق
• الطاقة الشمسية: اضبط الطاقة على 0 كيلووات لمدة ساعة في كل 30 دقيقة

تستجيب Sofar EMS برسالة تأكيد تحتوي على معرف الجدول الفريد، أو رسالة خطأ.

ثم نسترد الجدول التالي لكلا نوعي الأجهزة، مؤكدين أن الأمر كان ناجحًا.

يرجى تنزيل الملف أدناه في بيئة تطوير بايثون المفضلة لديك. املأ رقمك التسلسلي وبيانات اعتماد MQTT الخاصة بك ثم نفذ البرنامج النصي:

عند نجاح الخطوات السابقة، يمكنك المتابعة بإرسال أنواع أخرى من الرسائل. جميع الرسائل موصوفة أدناه.

توثيق MQTT لإرسال الأوامر

يشرح هذا القسم تنسيق رسائل MQTT ومتطلبات الحمولة لإعداد التحكم المجدول للأجهزة ضمن شبكة Sofar EMS.

موضوعات MQTT

• موضوع الاشتراك: standard1/rp_one_s/remoteScheduleMetrics/<controller SN>
• موضوع التعليقات: standard1/outbound/remoteScheduleMetrics/feedback/<controller SN>

حيث يجب استبدال <controller SN> برقم السيريال الفعلي لـ Sofar EMS الذي تنوي التحكم فيه.

أنواع رسائل MQTT

1. ضبط الجدول (set_schedule)

إنشاء جدول جديد لنوع جهاز.

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": <Unix Timestamp>,
    "message_type": "set_schedule",
    "fields": {
        "device_type": "<Device Type>",
        "node_id": "<Node ID>" (اختياري),
        "start_time": <Unix Timestamp>,
        "end_time": <Unix Timestamp>,
        "policy": "<Policy>",
        "power_setpoint_w": <Setpoint in watts>,
        "replace_overlap": <True/False> (اختياري) (افتراضي=False),
    }
}

استجابة (نجاح):

{
    "requestTime": <Unix Timestamp>,
    "time": <Unix Timestamp>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "set_schedule_ack",
        "state": {
            "schedule_id": <Schedule ID>,
            "deleted_ids": <Schedulde IDs deleted if replace_overlap=True>
        },
        "responseCode": 0
    }
}

2. الحصول على الجدول (get_schedule)

استرجاع جدول محدد بواسطة ID.

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": <Unix Timestamp>,
    "message_type": "get_schedule",
    "fields": {
        "id": <Schedule ID>
    }
}

استجابة:

{
    "requestTime": <Unix Timestamp>,
    "time": <Unix Timestamp>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "get_schedule_ack",
        "state": <Schedule>,
        "responseCode": 0
    }
}

3. الحصول على الجدول النشط (get_active_schedule)

استرجاع الجدول النشط حاليًا لنوع جهاز.

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": <Unix Timestamp>,
    "message_type": "get_active_schedule",
    "fields": {
        "device_type": "<Device Type>",
        "node_id": "<Node ID>" (اختياري),
    }
}

استجابة (نجاح):

{
    "requestTime": <Unix Timestamp>,
    "time": <Unix Timestamp>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "get_active_schedule_ack",
        "state": <Schedule>,
        "responseCode": 0
    }
}

4. الحصول على الجدول التالي (get_next_schedule)

استرجاع الجدول القادم لنوع جهاز.

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": <Unix Timestamp>,
    "message_type": "get_next_schedule", 
    "fields": {
        "device_type": "<Device Type>",
        "node_id": "<Node ID>" (اختياري),
    }
}

استجابة (نجاح):

{
    "requestTime": <Unix Timestamp>,
    "time": <Unix Timestamp>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "get_next_schedule_ack",
        "state": <Schedule>,
        "responseCode": 0
    }
}

5. الحصول على الجداول (get_schedules)

استرجاع جميع الجداول لتاريخ محدد.

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": <Unix Timestamp>,
    "message_type": "get_schedules",
    "fields": {
        "date": "<Date String of Format dd/mm/yyyy>"
    }
}

Response (Success):

{
    "requestTime": <Unix Timestamp>,
    "time": <Unix Timestamp>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "get_schedules_ack",
        "state": {
            "schedules": [<Schedule>, ...]
        },
        "responseCode": 0
    }
}

6. احصل على الجداول المستقبلية (get_future_schedules)

يسترجع جميع الجداول المستقبلية.

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": <Unix Timestamp>,
    "message_type": "get_future_schedules",
    "fields": {}
}

Response (Success):

{
    "requestTime": <Unix Timestamp>,
    "time": <Unix Timestamp>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "get_future_schedules_ack",
        "state": {
            "schedules": [<Schedule>, ...]
        },
        "responseCode": 0
    }
}

7. إزالة جدول (remove_schedule)

يزيل جدولاً محدداً بواسطة المعرف.

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": <Unix Timestamp>,
    "message_type": "remove_schedule",
    "fields": {
        "id": <Schedule ID>
    }
}

Response (Success):

{
    "requestTime": <Unix Timestamp>,
    "time": <Unix Timestamp>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "remove_schedule_ack",
        "state": "تم إزالة الجدول <Schedule ID> بنجاح",
        "responseCode": 0
    }
}

8. احصل على ملاحظات الموقع (get_feedback)

يسترجع ملاحظات تفصيلية حول حالة النظام.

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": <Unix Timestamp>,
    "message_type": "get_feedback",
    "fields": {}
}

Response (Success):

هيكل بيانات الملاحظات

تنسيق استجابة الجدول القياسي

{
    "id": <Schedule ID>,
    "device_type": "<Device Type>",
    "node_id": "<Node ID>" (اختياري),
    "start_time": <Unix Timestamp>,
    "end_time": <Unix Timestamp>,
    "policy": "<Schedule Policy>",
    "power_setpoint_w": <Setpoint in watts>,
    "created_at": <Unix Timestamp>
}

أنواع المكونات والسياسات

للحصول على تفاصيل حول المكونات المتاحة والسياسات التي يمكن جدولتها، يرجى الرجوع إلى قسم مكونات وسياسات MQTT في وثائق التحكم في MQTT المباشرة.

يمكن إرسال الجداول الخاصة بالجهاز باستخدام الحقل الاختياري node_id، الذي يشير إلى معرف العقدة للجهاز القابل للتحكم.

معالجة الأخطاء

يمكن لجميع الرسائل أن تعود باستجابة خطأ مع responseCode: 1 عندما يحدث خطأ:

{
    "requestTime": <Unix Timestamp>,
    "time": <Unix Timestamp>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "<Message Type>_ack",
        "error": <Error Body>,
        "responseCode": 1
    }
}

عندما يحدث خطأ غير متعلق، سيكون نوع الرسالة هو (general_error).

تشمل الأخطاء الشائعة:

• تداخل الجدول مع الجداول الموجودة
• نطاق زمني غير صالح
• نوع الجهاز غير موجود
• معرف الجدول غير موجود
• سياسة غير صالحة لنوع الجهاز

قواعد إدارة الجداول

1. قواعد التداخل
   • لا يمكن أن تتداخل الجداول لنفس نوع الجهاز
   • لا يمكن أن تتداخل الجداول لنفس الجهاز
   • لا يمكن أن تتداخل الجداول لنفس الجهاز ونوع الجهاز
   • سيتم حذف الجداول الموجودة والمتداخلة إذا تم تعيين المتغير replace_overlap إلى True عند إنشاء جدول جديد.
2. يجب أن يحتوي كل جدول على:
   • نوع جهاز صالح
   • وقت بدء (طابع زمني يونيكس)
   • وقت انتهاء (طابع زمني يونيكس)
   • سياسة (مطابقة لسياسات النوع المتاحة للجهاز)
   • نقطة ضبط الطاقة (للسياسات التي تتطلب ذلك)
3. يجب أن يكون وقت البدء قبل وقت الانتهاء
4. يجب أن يكون وقت البدء على الأقل خمسة دقائق في المستقبل
5. يمكن حذف الجداول فقط إذا كانت تبدأ بعد خمسة دقائق على الأقل في المستقبل
6. يمكن تعيين الجداول لأنواع أجهزة مختلفة بشكل مستقل
7. يقوم النظام تلقائيًا بتطبيق السياسة المناسبة عندما يصبح الجدول نشطًا